Allow Pending Work to Specialize Abort Reasons

Summary

Fizz currently reports every unfinished task using the same request-wide abort reason. This makes it possible to observe that a render did not finish, but not to understand why any individual suspended slot remained incomplete.

This change allows suspended tasks to report a more specific rejection reason when the wakeable they are blocked on rejects after abort begins and before Fizz finalizes that task. Tasks that do not reject during this window continue to report the general abort reason.

This is primarily motivated by partial prerendering, where aborting is not merely an exceptional termination mechanism. It is the API used to intentionally finish a prerender while leaving some work unresolved.

Motivation

For an ordinary server render, a request abort generally means that the result is no longer needed. Reporting the same abort reason for every unfinished task is usually sufficient.

For a partial prerender, the meaning is different. The caller intentionally aborts in order to produce a partial result. The unfinished work is then useful information: it identifies which parts of the tree prevented the prerender from completing.

Today, all of those tasks receive the same abort reason:

slot A -> prerender aborted
slot B -> prerender aborted
slot C -> prerender aborted

That says which work was incomplete, but not whether different slots should be interpreted differently.

For example, an application may have:

• A slow API that is permitted to miss the prerender deadline and should not produce actionable logging.
• Other work that is expected to finish during prerendering and should be reported when it does not.
• A data source that can provide additional telemetry about why it did not finish once it learns that the prerender has been aborted.

With a single request-wide abort reason, onError cannot distinguish these cases.

Proposed Behavior

When abort begins, Fizz still associates a general abort reason with the request. That reason remains the fallback for every unfinished task.

However, if a task is suspended on a wakeable and that wakeable rejects during the interval between:

1. The request beginning to abort.
2. Fizz finalizing that task as aborted.

then Fizz reports the wakeable's rejection reason for that task instead of the general abort reason.

Conceptually:

slot A -> rejected during abort with TimeoutError("optional recommendations timed out")
slot B -> still pending when abort finishes -> Error("prerender deadline reached")
slot C -> rejected during abort with QueryError("inventory lookup canceled")

A rejection that arrives after its task has already been finalized is ignored.

Intended Usage

The canonical usage is for the caller to use the same AbortSignal both to terminate the prerender and to notify data sources that may still be blocking suspended work.

const controller = new AbortController();

const result = prerender(<App signal={controller.signal} />, {
  signal: controller.signal,
  onError(error) {
    if (controller.signal.aborted) {
      // Interpret errors from unfinished work after the prerender deadline.
    } else {
      // Interpret ordinary rendering errors.
    }
  },
});

controller.abort(new Error('prerender deadline reached'));

An interested data source can observe that signal and reject pending work with a reason specific to the blocked operation:

signal.addEventListener('abort', () => {
  reject(new TimeoutError('optional recommendations timed out'));
});

Tasks blocked on such work can now report that specialized reason. Tasks blocked on work that does not participate in the abort still report the request-wide abort reason.

This allows applications to:

• Suppress logging for intentionally optional or deadline-limited work.
• Surface unfinished work that should be investigated.
• Include operation-specific telemetry or context in aborted-slot reporting.

Causality And Scope

Fizz does not attempt to prove that a wakeable rejected because of the abort signal.

The precise behavior is temporal:

• If a suspended wakeable rejects after abort begins and before its task is finalized, its rejection specializes that task's abort reason.
• If it does not reject during that interval, the task receives the general abort reason.
• If it rejects after finalization, the rejection is ignored for Fizz error reporting.

Using the same AbortSignal to notify data sources is the intended protocol, but Fizz cannot distinguish a rejection caused by that signal from any unrelated rejection that happens to occur during the abort window.

Likewise, signal.aborted in onError lets callers distinguish errors observed before abort initiation from errors observed after it began. It does not independently prove causality for an arbitrary rejection.

Implementation

Previously, a suspended task attached the same ping callback for both fulfillment and rejection:

wakeable.then(ping, ping);

That is correct during ordinary rendering because retrying the task allows a rejected wakeable to throw through the normal render path, preserving regular error handling and stack construction.

During abort, however, retrying general work is intentionally suppressed. To preserve a rejection that arrives during the abort window, the task now stores distinct fulfillment and rejection ping callbacks:

wakeable.then(ping.resolve, ping.reject);

Before abort begins, ping.reject retains existing behavior by scheduling the task for retry.

After abort begins, ping.reject attempts to claim the still-pending aborted task from its owning abort set. If successful, Fizz finalizes that task immediately using the rejection reason. The later scheduled abort finish processes only tasks that remain in their abort sets, using the general abort reason.

This avoids adding another top-level property to Task, whose production shape is already at the current field-count threshold, while also covering suspension mechanisms such as React.lazy that cannot be handled by inspecting use() thenable state.

Tests

The tests cover:

• A rejected suspended task reporting a specialized reason while unrelated pending work still reports the general abort reason.
• Specialization for React.lazy, ensuring this is not limited to use() suspension.
• A rejection arriving after abort finalization being ignored.
• The prerender scheduling window in both static Browser and Node APIs, where abort listeners can reject pending work before abort completion.